`co(4,7);─────────────────────── /// Rectangle Functions ──────────────────────────────`co();

 ┌──────────────────────────────────────────────────────────────────────────┐	
 │          `keyword(set_rect,/// set_rect);                  `keyword(rect_equal,/// rect_equal);        `keyword(rect_overlap,/// rect_overlap);        │
 │          `keyword(offset_rect,/// offset_rect);               `keyword(cr_inrect,/// cr_inrect);                             │
 └──────────────────────────────────────────────────────────────────────────┘

		The UltraWin library uses the structure RECT to handle information
	dealing with rectangular sections of the screen, as in the WINDOW
	structure.	Included are functions to define the rectangle, check to see
	if one rectangle overlaps another, and several other routines that you may
	wish to utilize in your program.

`co(10,1);/// set_rect`co();   `keyword(source,[UW_WIN.C]~set_rect);
		Takes the variable of type RECT passed by pointer, and sets the upper
	left corner and lower right corner to the coordinates passed as integers.

Prototype:
	void set_rect(RECT *rectp, int x1, int y1, int x2, int y2);

Parameters:
`co(11,1);	RECT *rectp;`co();
		A pointer to the rectangle variable.
`co(11,1);	int x1, y1, x2, y2`co();
		The coordinate pair for the upper left corner (x1,y1) and the lower
		right corner (x2,y2) of the rectangle.

Usage:
	RECT r;
	...
	set_rect( &r, 10, 10, 20, 20 );

`co(10,1);/// rect_equal`co();   `keyword(source,[UW_WIN.C]~rect_equal);
		Checks to see if the two rectangles are the same.

Prototype:
	int rect_equal(RECT r1, RECT r2);

Parameters:
`co(11,1);	RECT r1, r2;`co();
		The two rectangles to compare.

Usage:
	RECT r1, r2;
	...
	if (rect_equal( r1, r2 )) {}

`co(10,1);/// rect_overlap`co();   `keyword(source,[UW_WIN.C]~rect_overlap);
		Reports on the relationship between two rectangles.  This function will
	return the status as one of the following (defined in UW.H):

		1) FIRST_ENCLOSED
				 The first rectangle is enclosed within the second.
		2) SECOND_ENCLOSED
				 The second rectangle is enclosed within the first.
		3) OVERLAP
				 The rectangles overlap.
		4) NO_OVERLAP
				 The rectangles do not overlap.

Prototype:
	int rect_overlap(RECT *r1, RECT *r2);

Parameters:
`co(11,1);	RECT r1, r2;`co();
		The two rectangles whose relationship to find.

Usage:
	RECT r1, r2;
	int status;
	...
	status = rect_overlap( r1, r2 );

`co(10,1);/// offset_rect`co();   `keyword(source,[UW_WIN.C]~offset_rect);
		Moves the rectangles coordinates by a fixed positive or negative amount
	in both the x (column) and y (row) direction.

Prototype:
	void offset_rect(RECT *rectp, int col, int row);

Parameters:
`co(11,1);	RECT *rectp;`co();
		A pointer to the rectangle variable.
`co(11,1);	int col, row`co();
		The offsets to add to the rectangle's coordinates.

Usage:
	RECT r;
	...
	offset_rect( &r, 5, -4 );

`co(10,1);/// cr_inrect`co();   `keyword(source,[UW_WIN.C]~cr_inrect);
		Checks to see if a particular location is inside (or on the border of)
	the rectangle passed.

Prototype:
	int cr_inrect(int col, int row, RECT rect);

Parameters:
`co(11,1);	int col, row`co();
		The coordinate to see if it lies in the rectangle.
`co(11,1);	RECT r;`co();
		The rectangle to check.

Usage:
	RECT r;
	...
	if (cr_inrect( 5, 5, r )) {}

`co(4,7);──────────────────────────── /// Data Entry ──────────────────────────────────`co();

 ┌──────────────────────────────────────────────────────────────────────────┐	
 │           `keyword(wn_gets,/// wn_gets);                            `keyword(Masks/Templates,/// Masks/Templates);             │
 │           `keyword(Validation Chars,/// Validation Chars);                   `keyword(Strip Mask Option,/// Strip Mask Option);           │
 │           `keyword(wn_gets_ll,/// wn_gets_ll);                            					             		│
 └──────────────────────────────────────────────────────────────────────────┘

	  One of the most flexible of all functions in the UltraWin library is
	wn_gets.  With this one function you can have the user enter dates, times,
	prices, strings, and any other type will full control over every character
	entered!  UltraWin versions 2.00 and up add an even more powerful lower
	level function now called by wn_gets to enhance the capabilities even
	further.  Full compatibility is maintained.  The new function called
	wn_gets_ll has added the capability to uppercase the first character of
	each word, strip the mask completely, only strip the end, or not strip at
	all.  It can also get input right-to-left, clear an input on the first
	non-keypad keypress, and exit when the last character in the input is
	entered, saving an extra <Enter> keypress.  Furthermore it can allow the
	user to input a string longer than the display width of the field and will
	scroll within this region automatically!  It can also display arrows to
	show the user that the string has data to the left or right of the current
	display field.  If this isn't enough for you, we've added the ability to
	call your own validation function for every character entered in
	wn_gets_ll.  This allows you to validate the user's input "as it happens",
	and enhance wn_gets_ll. A new wn_gets_ll hook added in version 2.10 allows
	both pre and post processing, as well as the ability to modify the event
	itself, giving you the ability to translate keys.
	
	See also `keyword(set_validation_func,/// set_validation_func);.

`co(10,1);/// wn_gets`co();   `keyword(source,[UW_ENTRY.C]~wn_gets);
		Gets input from the user according to the restrictions of the mask and
	template strings in the window passed by pointer.  This function will pass
	back the input either with the mask characters included in the string, or
	stripped out.	A -1 is returned if the mouse is clicked off of the string,
	and one of the values KEY_UP, KEY_DN, KEY_PGUP, KEY_PGDN, KEY_ESC,
	KEY_ENTER or KEY_TAB (all defined in UW.H) is returned if pressed.  Read
	about the mask and template strings for more information.

Prototype:
	int wn_gets( char *str, char *mask, char *template, int m_att,
							 int strip_mode, WINDOW *wnp );

Parameters:
`co(11,1);	char *str`co();
		The string to be returned by the function.
`co(11,1);	char *mask`co();
		The mask string.
`co(11,1);	char *template`co();
		The template string.
`co(11,1);	int m_att`co();
		The attribute (colors) to use when displaying the string.
`co(11,1);	int strip_mode`co();
		Set to 1 (STRIP_ON) to strip mask characters out of result, or set to 0
		(STRIP_OFF) for full mask and result.
`co(11,1);	WINDOW *wnp;`co();
		A pointer to the window in which entry is to take place.

Usage:
	WINDOW *wnp;
	int result;
	char s[80];
	...
	result = wn_gets( s, "(___)-___-____", "###  ### ####",
										wnp->att, STRIP_ON, wnp);

`co(10,1);/// Masks/Templates`co();

	The wn_gets function requires you to specify two important strings to
	perform its magic.  These are the mask and template strings.

	The mask string gives you the flexibility of displaying textual
	information inside the area to be typed by the user.	The mask characters
	are displayed in each position of the string that does not have text.

	The template string is essentially a string containing validation
	characters.  Before a character is entered into the string, the wn_gets
	function compares the typed character with the template to see if the
	character is valid.  In addition, the template can be used to force an
	uppercase or lowercase character without having the user touch the
	CapsLock or Shift keys.

	When combined, the mask and template strings give you great flexibility.
	The following are just a few examples with explanations of what they
	accomplish:

	mask = "________"           Enter an 8 character string, where all
	tplt = "AAAAAAAA"           characters must be alphanumeric.
	
	mask = "________"           Enter an 8 character string, where
	tplt = "********"           anything typed is valid.
	
	mask = "________"           Enter an 8 character string, where the
	tplt = "Uaaaaaaa"           first character is converted to
															uppercase, and the rest must be alpha.
	
	mask = "________"           Enter an 8 character string, where all 8
	tplt = "uuuuuuuu"           characters must by typed in uppercase.

	mask = "(___) ___-____"     Enter a 14 character string, where only
	tplt = " ###  ### ####"     numbers can be typed at the _ positions.


`co(10,1);/// Validation Chars`co();

	Validation characters are simply characters that are valid to put in your
	templates.	The following is a list of the validation characters along
	with their effect.
	
	Validation Char 		 Effect
	--------------- 		 -----------------------------------------------
			 '#'             Allows only a digit to be entered.
			 '9'             Allows digits, '+', '-', '.', 'E', and 'e'.
			 'X'             Allows only a hexidecimal digit to be entered.
			 'u'             Allows only upper case letters to be entered.
			 'l'             Allows only lower case letters to be entered.
			 'U'             Converts to upper case, even if typed as lower.
			 'L'             Converts to lower case, even if typed as upper.
			 'A'             Allows only alphanumeric characters and <space>.
			 'a'             Allows only alpha characters and <space>.
			 '*'             Allows any characters.

`co(10,1);/// Strip Mask Option`co();

	This parameter to the wn_gets function gives you the option to have
	wn_gets either format the string with the mask characters intact, or strip
	out the mask characters.	This can best be demonstrated as follows:

	mask = "(___) ___-____"
	tplt = " ###  ### ####"
	
	When wn_gets is called with these parameters, and a phone number is
	entered, the display looks like this:
	
														(123) 456-7890

	Very simply, if the strip mask option is not used, then this string is
	what is returned by the function (mask intact).	 However, if the strip
	mask option is used, then the returned string would be:
	
															 1234567890

	with no mask characters left, only what the user typed!  By utilizing this
	parameter in appropriate places you can save yourself a considerable
	amount of work.

`co(10,1);/// wn_gets_ll`co();   `keyword(source,[UW_ENTRY.C]~wn_gets_ll);
		Has the same capabilities as wn_gets and more.  Wn_gets_ll has the
	capability to uppercase the first char of each word, strip the mask
	completely, only strip the end, or not strip at all.  Right-to-left input,
	clear entry on first key, and auto-return is also supported.  The function
	will also allow the user to input a string longer than the display width
	of the field and will scroll within this region automatically.  It can
	also display arrows to show the user that the string has data to the left
	or right of the current display field.  We've added the ability to call
	your own validation function for every character entered in wn_gets_ll.
	This allows you to validate the user's input "as it happens", and
	customize the validation routine.  See `keyword(set_validation_func,/// set_validation_func); for more
	information.

		Starting with version 2.10 we've added a powerful hook into this
	function that is called on entry, exit, and on every keypress.  It is
	similar to the validation function except that wn_gets_ll expects a return
	key value from the function, giving the hook the ability to translate
	keystrokes.  See `keyword(set_gets_hook,/// set_gets_hook); for more details.
  

Prototype:
	int wn_gets_ll(	char *str, char *mask, char *template, int m_att,
									int flags, int disp_width, WINDOW *wnp );

Parameters:
`co(11,1);	char *str`co();
		The string to be returned by the function.
`co(11,1);	char *mask`co();
		The mask string.
`co(11,1);	char *template`co();
		The template string.
`co(11,1);	int m_att`co();
		The attribute (colors) to use when displaying the string.
`co(11,1);	int flags`co();
   `co(15,1);G_STRIP`co();        		strips the entire mask from the string.
                		* 12/04/91 = 120491, (432)-555-3421 = 4325553421

   `co(15,1);G_STRIP_END`co();    		strips the end of the string only.
                		* John Doe____ = John Doe

   `co(15,1);G_UP_FST_CHAR`co();  		convert the first letter of each word to uppercase
                		* this is a test = This Is A Test

   `co(15,1);G_ARROW`co();        		displays left and right arrows if display width is less
                  		than field width. NOTE: This requires an additional
                  		screen/window space before and after the field.

   `co(15,1);G_VALIDATE`co();     		call the validation function set by `keyword(set_validation_func,/// set_validation_func); 

   `co(15,1);G_RIGHT_TO_LEFT`co();  	gets input from the right side of the string.

   `co(15,1);G_CLEAR_ON_FIRST`co(); 	clears the entry string when the first valid non-keypad
											key is pressed.

   `co(15,1);G_EXIT_ON_FILL`co(); 		returns when the last character in the entry is typed,
 											saving the user an <Enter> keypress.
`co(11,1);	int disp_width`co();
		The number of characters to display.  If less than the length of the
		input field, the display field will scroll.
`co(11,1);	WINDOW *wnp;`co();
		A pointer to the window in which entry is to take place.

Usage:
	WINDOW *wnp;
	int result;
	char s[80];
	...
/*---- strip mask, convert first character of each word to uppercase, -----*/
/*------- and only display 6 characters, using arrows to show more --------*/
	result = wn_gets_ll( s, "______________", "AAAAAAAAAAAAA", wnp->att,
											 G_STRIP | G_UP_FIRST_CHAR | G_ARROW, 6, wnp);

`co(10,1);/// set_validation_func`co();   `keyword(source,[UW_ENTRY.C]~set_validation_func);
		Allows you to set your own data entry validation function that is
	called every time a character is typed in `keyword(wn_gets_ll,/// wn_gets_ll);.  Note that this is
	not necessarily called for every keystroke. If the user pressed the arrow
	keys, backspace, etc. the function will not be called.  It is called only
	when entering data.  (If you wish to process every keystroke, see
  `keyword(set_gets_hook,/// set_gets_hook);.)  When the function is called it is passed a series of
	parameters that allow complete flexibility.  The validation routine should
	return a 1 if all's well, else it should return a 0.  If 0 is returned,
	the entry routine will overwrite the invalid character with the mask
	character for the current position.  See the demo program `keyword(str_demo,[STR_DEMO.C]main);
	for more details.

Prototype:
	void set_validation_func( int (*func_ptr)() );

Parameters:
`co(11,1);	int (*func_ptr)()`co();
		A function pointer which is called for each character entry.

Usage:
	set_validation_func( date_vld );
	...
	int date_vld( char *w, char *t, char *m, int pos, int max_pos,
								WINDOW *wnp )
	{
		/* w       - pointer to current work string */
		/* m       - pointer to the mask            */
		/* t       - pointer to the template        */
		/* pos     - current cursor position        */
		/* max_pos - maximum cursor position        */
		/* wnp     - pointer to the entry window (use for err msg, etc) */
	}

`co(10,1);/// set_gets_hook`co();   `keyword(source,[UW_ENTRY.C]~set_gets_hook);
		Allows you to set your own hook to be called from `keyword(wn_gets_ll,/// wn_gets_ll);.  Your
	hook will be called on entry, exit, and every time a key is pressed.
	Wn_gets_ll will call your function, passing the work string, template,
	mask, cursor position, maximum cursor position, the process type,
	a pointer to the global Event, and the window pointer for the entry.
	
	  NOTE:  The process type can be one of the three defines ( in UW.H )
	H_ENTRY, H_EXIT, or H_PROCESS.  Wn_gets_ll calls your hook on function
	entry, exit, and every time a key is pressed.  You may modify any of the
	strings passed, or even modify the key value.  If you wish to modify the
	key, simply set event->key inside your routine.  This will allow you to
	remap any of the keys used in the entry routine to ones your might like
	more.
	
	
Prototype:
	void set_gets_hook( int (*func_ptr)() );

Parameters:
`co(11,1);	int (*func_ptr)()`co();
	  A pointer to the function to call.

Usage:
	set_gets_hook( super_hook );
	...
	int super_hook( char *w, char *t, char *m, int pos, int max_pos,
									int proc_type, EVENT *event, WINDOW *wnp );
	{
		/* w       		- pointer to current work string */
		/* t       		- pointer to the template        */
		/* m       		- pointer to the mask						 */
		/* pos     		- current cursor position        */
		/* max_pos 		- maximum cursor position        */
		/* proc_type	- defines H_ENTRY, H_EXIT or H_PROCESS */
		/* event			- pointer to the global Event variable */
		/* wnp    	 	- pointer to the entry window (use for err msg, etc) */
	}

`co(4,7);───────────────────────────── /// Menuing ────────────────────────────────────`co();

 ┌──────────────────────────────────────────────────────────────────────────┐	
 │          `keyword(menu_create,/// menu_create);             `keyword(menu_destroy,/// menu_destroy);          `keyword(menu_set,/// menu_set);          │ 
 │          `keyword(menu_restore,/// menu_restore);            `keyword(item_add,/// item_add);              `keyword(do_menu,/// do_menu);           │
 │          `keyword(menu_system,/// menu_system);                                                     │
 └──────────────────────────────────────────────────────────────────────────┘

	  UltraWin allows both vertical and horizontal menus to be easily created
	and displayed for interaction with the user.	The menu's entries can be
	selected with just one keystroke (or a simple click of the mouse).  The
	letter to check when selecting an entry can be any character of the entry,
	and can even be highlighted in a different color.  In addition, the menus
	can be defined as POPUP, restoring the area under the menu when finished,
	or they can be used with the window manager, forcing a redraw of
	overlapping areas of any windows under the menu.

`co(10,1);/// menu_create`co();   `keyword(source,[UW_MENU.C]~menu_create);
		Initializes the menu to the specified coordinates on the screen, the
	menu attributes (colors), the border style and menu type passed.  A call
	to this function must be made to define the menu before the menu is placed
	on the screen with menu_set.	For the type parameter, use WN_POPUP if you
	wish the menu to be a popup menu (restoring the screen below), or
	WN_NORMAL if you are using UltraWin's powerful window manager.

Prototype:
	void menu_create(int x_min, int y_min, int x_max, int y_max,
									 int direction, int back_att, int bdr_att, int csr_att,
									 int first_att, int bdr, int type, MENU *mnp);

Parameters:
`co(11,1);	int x_min, y_min`co();
		The upper left corner of the menu to create.
`co(11,1);	int x_max, y_max`co();
		The lower right corner of the menu to create.
`co(11,1);	int direction`co();
		The menu direction, use M_VERTICAL for a vertical menu and
		M_HORIZONTAL for a horizontal menu.
`co(11,1);	int back_att`co();
		The attribute to use for the menu.	This defines the color of
		the menu and the characters in the menu, and can be a value from
		0-255.	For example, use (RED << 4) | WHITE for white menu entry
		characters on a red background.
`co(11,1);	int bdr_att`co();
		The border attribute (not used if the bdr parameter is NO_BDR).
`co(11,1);	int csr_att`co();
		The attribute to use when displaying the cursor position.
`co(11,1);	int first_att`co();
		The attribute to use for the menu entry selection character.
		Typically you would use the same background color as back_att,
		but a different foreground color.
`co(11,1);	int bdr`co();
		The border style, can be either NO_BDR, SGL_BDR, DBL_BDR,
		SLD_BDR or DUAL_BDR (defined in uw.h).
`co(11,1);	int type`co();
		The menu type, can be either WN_POPUP or WN_NORMAL.  Use the
		former when not using the window manager.
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to create.

Usage:
	MENU mn;
	int back_att, bdr_att, csr_att, first_att;
	...
	menu_create(0, 0, 20, 10, M_VERTICAL, back_att, bdr_att,
							csr_att, first_att, SGL_BDR, WN_NORMAL, *mn);

`co(10,1);/// menu_destroy`co();   `keyword(source,[UW_MENU.C]~menu_destroy);
		Destroys the menu created with menu_create.  The window allocated for
	the menu is freed.
		
Prototype:
	void menu_destroy( MENU *mnp );

Parameters:
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to destroy.

Usage:
	MENU *mnp;
	...
	menu_destroy(mnp);

`co(10,1);/// menu_set`co();   `keyword(source,[UW_MENU.C]~menu_set);
		Takes a menu created with menu_create, and places it on the screen.  If
	the menu was defined with type WN_POPUP, the area below the window is
	saved for later restoration.

Prototype:
	void menu_set( MENU *mnp );

Parameters:
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to place on the screen.

Usage:
	MENU *mnp;
	...
	menu_set(mnp);

`co(10,1);/// menu_restore`co();   `keyword(source,[UW_MENU.C]~menu_restore);
		Takes a menu created with menu_create, placed on the screen with
	menu_set, and removes it from the screen.  If the menu was defined with
	type WN_POPUP, the area below the window is restored.  If the menu was
	defined with type WN_NORMAL and the window manager is in use, then the
	area under the menu will be redrawn.

Prototype:
	void menu_restore( MENU *mnp );

Parameters:
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to restore.

Usage:
	MENU *mnp;
	...
	menu_restore(mnp);

`co(10,1);/// item_add`co();   `keyword(source,[UW_MENU.C]~item_add);
		Adds an entry into a menu.	An integer handle (or id) that you define is
	passed to identify the entry. The menu_do function returns this id when
	the entry is selected. In addition, the index into the string for the
	"active" character is passed.	This is the character in the string that is
	displayed in the first_att color upon display, and is used when a key on
	the keyboard is pressed that matches.

Prototype:
	void item_add( char *entry, int id, int first_pos, MENU *mnp );

Parameters:
`co(11,1);	char *entry;`co();
		The string to add to the menu.	This string does not have to be the same
		length as the width of the menu, as the display routines of menu_set and
		menu_do justify the entry for you.
`co(11,1);	int id`co();
		This is an id you define which will be returned to you when the menu
		item is selected in menu_do.
`co(11,1);	int first_pos`co();
		This is an index into the string for the "active" letter.  This letter
		will be used to check against keyboard letters pressed, and will be
		displayed in the first_att color specified in the menu_create function.
		For example, for the entry "Dos Shell" to make the menu_do function
		return the id with one keypress, use a first_pos of 4, which corresponds
		to the "S" in "Shell".
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu to which the item is to be added.

Usage:
	#define DOS_SHELL 37
	MENU *mnp;
	...
	item_add("Dos Shell", DOS_SHELL, 4, mnp);

`co(10,1);/// do_menu`co();   `keyword(source,[UW_MENU.C]~do_menu);
		Activates a menu for input from the user.	Call this function after you
	have called menu_set.  To retain flexibility, you may specify whether the
	do_menu function should interact with the user through the wait_event
	function, or immediately process the global Event variable and return to
	you.	This gives you the ability to use your own event logic if you wish,
	and is useful for menus which are static on the screen, as opposed to
	menus that pop up and restore when finished.	If interaction through
	wait_event is specified, then this function returns either the id of the
	item selected, or 0 if no item is selected. If you have do_menu only
	process the information in the global variable Event, then a 0 is returned
	for each call to do_menu that does not have an <Enter> keypress in Event.

Prototype:
	int do_menu( MENU *mnp, int proc_mode );

Parameters:
`co(11,1);	MENU *mnp;`co();
		A pointer to the menu for interaction.
`co(11,1);	int proc_mode`co();
		The processing mode, which can be one of the defines M_GET_EVENT or
		M_PROC_EVENT.	If M_GET_EVENT is used, then the menu will get input via
		the keyboard (or mouse if it exists) until the user has either selected
		one of the items, or pressed the Esc key.

Usage:
	MENU *mnp;
	...
	do_menu( mnp, M_GET_EVENT );

`co(10,1);/// menu_system`co();   `keyword(source,[UW_MENU.C]~menu_system);
		Was written specifically for the standard top menu bar with
	corresponding drop down menus.  Menu_system gives you the option of
	displaying the top menu upon entry and removing the top menu upon exit (a
	popup menuing system), or simply use the top menu previously placed on the
	screen with menu_set.  When called, the function will interact with the
	user through the keyboard and mouse, and return the menu id of the entry
	selected.  If the Esc key was pressed or the mouse clicked off the menu,
	then a 0 is returned.  Upon completion, the global Event variable will
	contain information about the last key or mouse press.

	NOTE: To utilize this function, you must first define your menus with
	menu_create, then add each entry with item_add, being sure to define a
	unique id for each entry.

Prototype:
	int menu_system( MENU *top_mnp, MENU *dropmenu[], int draw_top );

Parameters:
`co(11,1);	MENU *top_mnp;`co();
		A pointer to the vertical main menu.
`co(11,1);	MENU *dropmenu[];`co();
		An array of pointers to a series of drop down menus.
`co(11,1);	int draw_top`co();
		This parameter can be either 1 or 0, and specifies whether the
		menu_system function should handle the initial display of the top menu
		or assume that the top menu is already displayed. Using a value of 1 is
		useful if you wish your menu system to be hidden during your program,
		and only called up with a key.	Use a 0 for when your program keeps the
		top menu on the screen.

Usage:
	MENU *top_mnp;
	MENU *drop_mnp[8];
	...
	menu_system( top_mnp, drop_mnp, 1);
